Saving Image Files16

Graphics import components can save data in several formats, including QuickDraw pictures and QuickTime Image files. This capability is only needed by applications that perform file format translation. Applications that only wish to draw the image can use the GraphicsImportDraw function.

GraphicsImportSaveAsPicture

Creates a QuickDraw picture file.



 
pascal ComponentResult GraphicsImportSaveAsPicture (

                     GraphicsImportComponent ci,

                     const FSSpec *fss,

                     ScriptCode scriptTag);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
fss: A pointer to the file that is to receive the image.
scriptTag: Specifies the script system in which the file name is to be displayed. If you have established the name and location of the file using one of the Standard File Package functions, use the script code returned in the reply record (reply.sfScript ). Otherwise, specify the system script by setting the scriptTag parameter to the value smSystemScript . See Inside Macintosh: Files for more information about script specification.

DISCUSSION

This function creates a new QuickDraw picture file containing the image currently in use by the graphics import component. If possible, the image will remain in the compressed format. For example, if the image is from a JFIF file, the picture will contain compressed JPEG data.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

File system errors

GraphicsImportSaveAsQuickTimeImageFile

Creates a QuickTime Image file.



 
pascal ComponentResult GraphicsImportSaveAsQuickTimeImageFile (

                     GraphicsImportComponent ci,

                     const FSSpec *fss,

                     ScriptCode scriptTag);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
fss: A pointer to the file that is to receive the image.
scriptTag: Specifies the script system in which the file name is to be displayed. If you have established the name and location of the file using one of the Standard File Package functions, use the script code returned in the reply record (reply.sfScript ). Otherwise, specify the system script by setting the scriptTag parameter to the value smSystemScript . See Inside Macintosh: Files for more information about script specification.

DISCUSSION

This function creates a new QuickTime Image file containing the image currently in use by the graphics import component. If possible, the image will remain in the compressed format. For example, if the image is from a JFIF file, the QuickTime Image file will contain compressed JPEG data.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

File system errors

GraphicsImportGetAsPicture

Creates a QuickDraw picture handle.



 
pascal ComponentResult GraphicsImportGetAsPicture (

                     GraphicsImportComponent ci,

                     PicHandle *picture);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
picture: Points to a picture handle that is to receive the image.

DISCUSSION

This function creates a new QuickDraw picture handle containing the image currently in use by the graphics import component. If possible, the image will remain in the compressed format. For example, if the image is from a JFIF file, the picture will contain compressed JPEG data. It is the responsibility of the caller to dispose of the picture handle using KillPicture .

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportExportImageFile

Saves an image in a foreign file format.



 
 pascal ComponentResult GraphicsImportExportImageFile (GraphicsImportComponent ci,

                     OSType fileType,

                     OSType fileCreator,

                     const FSSpec *fss,

                     ScriptCode scriptTag);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
fileType: The file type for the new image file, such as `JPEG' .
fileCreator: The file creator for the new image file. This parameter may be 0, in which case a default file creator for this file type is used.
fss: A pointer to the file that is to receive the exported image file.
scriptTag: Specifies the script system in which the file name is to be displayed. If you have established the name and location of the file using one of the Standard File Package functions, use the script code returned in the reply record (reply.sfScript ). Otherwise, specify the system script by setting the scriptTag parameter to the value smSystemScript . See Inside Macintosh: Files for more information about script specification.

DISCUSSION

This function creates a new file containing the image currently in use by the graphics import component. The new file is compressed in a format corresponding to the provided file type.

If a non-identity matrix has been applied to the graphics import component, this matrix is applied to the image before export. Since most image formats don't support nonzero top-left coordinates, the matrix is temporarily adjusted to ensure that the exported image's bounds have top-left coordinates at (0,0). If the matrix does not map the graphics import component's source rectangle to a rectangle, there will be extra white space left around the image.

In QuickTime 3, the supported export file types arekQTFileTypePicture, kQTFileTypeQuickTimeImage, kQTFileTypeBMP, kQTFileTypeJPEG, and kQTFileTypePhotoshop . QuickTime 4 uses graphics exporter components to implement image export.

RESULT CODES

`noErr`	0	No error
`dupFNErr`	-48	File already exists
`paramErr`	-50	Invalid parameter or unrecognized export file type

File Manager and Memory Manager errors

GraphicsImportGetExportImageTypeList

Returns information about available export formats.



 
pascal ComponentResult GraphicsImportGetExportImageTypeList (

                     GraphicsImportComponent ci,

                     QTAtomContainerPtr*);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
QTAtomContainerPtr: A pointer to a QT atom container to receive the type list.

DISCUSSION

This function creates and returns a QuickTime atom container containing information about the file types that can be exported by the graphics import component. It is the responsibility of the caller to dispose of this atom container.

In QuickTime 3, the supported export file types are kQTFileTypePicture, kQTFileTypeQuickTimeImage, kQTFileTypeBMP, kQTFileTypeJPEG, and kQTFileTypePhotoShop . For each file type, the atom container contains the following child atoms:

`kGraphicsExportFileType`	The exported file type
`kGraphicsExportMIMEType`	The MIME type for this format (optional)
`kGraphicsExportExtension`	The suggested file extension for this format
`kGraphicsExportDescription`	A human-readable name for this format

In QuickTime 4, the generic graphics importer builds this atom container from the values returned by the installed graphics exporter components.

The file type atom should contain an OSType; the other atoms should contain non-terminated strings.

Figure 16-5 shows a diagram of a QT atom container with the following atoms grouped.

Figure 5 A QT atom container

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter
`Memory Manager errors`

GraphicsImportDoExportImageFileDialog

Presents a dialog box letting the user save an image in a foreign file format.



 
pascal ComponentResult

                     GraphicsImportDoExportImageFileDialog ( 

                     GraphicsImportComponent ci,

                     const FSSpec *inDefaultSpec,

                     StringPtr prompt,

                     ModalFilterYDUPP filterProc,

                     OSType *outExportedType,

                     FSSpec *outExportedSpec,

                     ScriptCode *outScriptTag);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
inDefaultSpec: A pointer to an FSSpec suggesting the default name for the file. If you do not want to suggest a default name, pass nil .
prompt: A prompt that appears in the standard put dialog box; it may be nil, in which case a default string is used.
filterProc: A modal filter procedure to be passed to CustomPutFile . If you do not need to filter events, pass nil .
outExportedType: A pointer to a variable that will receive the file type that was chosen for export. If you do not want this information, pass nil .
outExportedSpec: A pointer to a variable that will receive the file that was written. If you do not want this information, pass nil .
outScriptTag: A pointer to a variable that will receive the script system in which the exported file name is to be displayed. If you do not want this information, pass nil .

DISCUSSION

This function presents the user with an extended Standard File dialog box which allows the image currently in use by the graphics import component to be exported to a file and in a format of the user's choice.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter or unrecognized export file type
`userCanceledErr`	-128	The user canceled the dialog box

File Manager and Memory Manager errors

GraphicsImportGetExportSettingsAsAtomContainer

Retrieves settings for exported image files.



 
 pascal ComponentResult

                     GraphicsImportGetExportSettingsAsAtomContainer (

                     GraphicsImportComponent  ci,

                     QTAtomContainerPtr*);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
QTAtomContainerPtr: A pointer to a QT atom container to receive the settings information.

DISCUSSION

This function creates and returns a new QuickTime atom container which holds information about how images will be saved by the GraphicsImportExportImageFile function. It is the responsibility of the caller to dispose of this atom container.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter
`memFullErr`	-108	Not enough memory available

GraphicsImportSetExportSettingsFromAtomContainer

Sets settings for exported image files.



 
 pascal ComponentResult

                     GraphicsImportSetExportSettingsFromAtomContainer (

                     GraphicsImportComponent ci,

                     QTAtomContainer*);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
QTAtomContainer: A pointer to a QuickTime atom container holding new settings information.

DISCUSSION

This function extracts export settings from a QuickTime atom container. These settings configure how images will be saved by the GraphicsImportExportImageFile function.

RESULT CODES

`noErr`	0	No error
`memFullErr`	-108	Not enough memory available.